Getting Started
Creating a New Feature
You can scaffold a mobile feature in two ways:
| Approach | Command | Best for |
|---|---|---|
| Offline starter | nx generate @cdx-extensions/widget-template-mobile:feature | Blank React Native library with no catalog |
| Catalog templates | nx run generate-mobile-feature | DI-backed starters from the extension template catalog |
Both create a correctly structured React Native library wired for @cdx-extensions/di-sdk (PlatformSDK), built with tsup, and aligned with the CDX mobile patterns used in the reference implementations.
The offline generator lives in @cdx-extensions/widget-template-mobile and uses the feature target by design — output is placed under features/mobile/ in the monorepo. You are scaffolding a feature even though the package name includes widget-template.
For catalog-driven generation (category picker, npm template overlays), see Extension Template Catalog. Quick reference:
nx run generate-mobile-feature # interactive: feature only
nx run generate-mobile-extensions # interactive: type → category → template → fiId → name
nx run generate-mobile-feature -- --template=agent-chat --fiId=0123 --name=acme-chat
Looking for an embedded home-screen component instead? See Widgets — Getting Started.
The Offline Starter Template
Use the offline starter when you want a blank scaffold without the catalog. The package @cdx-extensions/widget-template-mobile exposes a feature generator for full-screen experiences.
Prerequisites
Before you run the generator, complete the prerequisites and environment setup described in the CDX Extensibility Apps README.
When to Use a Feature
| Generator | Use when | Example |
|---|---|---|
feature | You are building a full-screen experience the host mobile banking app maps to a dedicated bottom tab, or surfaces in the More menu. |  Sample Feature — bottom tab with a full-screen experience |
Command
nx generate @cdx-extensions/widget-template-mobile:feature --fiId=<fi-id> --name=<name>
| Option | Required | Description |
|---|---|---|
--fiId | Yes | Your FI Id. Used as the package scope — the generated package name is @<fiId>-extensions/<name> |
--name | Yes | Name of the feature (e.g. account-summary). Used as the Nx project name and folder name |
Example
nx generate @cdx-extensions/widget-template-mobile:feature --fiId=0000 --name=my-feature
What Gets Created
Scaffolded under features/mobile/<name>/ by default:
features/mobile/my-feature/
├── src/
│ ├── my-feature.tsx ← feature component — start here
│ ├── index.ts ← named + default exports
│ ├── config.ts ← API base URL (baseUrl) and endpoint path (apiPath)
│ └── types/
│ └── branding.ts ← MobileBrandingTheme types and resolveColors helper
├── package.json
├── project.json
├── tsconfig.json
└── README.md
After You Generate
The generator registers your project in the sandbox automatically. From the repository root:
npm install
npx nx start mobile-sandbox
Press i for the iOS Simulator, a for Android Emulator, or scan the QR code with Expo Go on a physical device. The sandbox provides the mock platform (user context, branding, HTTP client) so your feature can run without the production host app.
For how features appear in the More menu and full-screen preview, see Mobile Playground — Feature Setup.
What You Can Edit
| File / Folder | Can you edit? | Notes |
|---|---|---|
src/ | Yes, freely | All your UI and business logic goes here |
package.json | Partially | Change name, version, peerDependencies. Keep the build scripts and tsup config as-is |
project.json | Partially | Only change name, outputs, and cwd to match your project folder |
tsconfig*.json | No | Required TypeScript config |
Common Mistakes to Avoid
| Mistake | Why It Breaks |
|---|---|
Using fetch() or Axios directly instead of sdk.getHttpClient() | Bypasses platform auth and security in production |
Importing from @cdx-extensions/di-sdk-mobile in feature code | Only the host app initialises the platform — features import from @cdx-extensions/di-sdk only |
| Adding peer or runtime dependencies outside the versions listed in the CDX Extensibility Apps README | Version conflicts with the host mobile banking app at runtime |
Forgetting to export from src/index.ts | The sandbox (or host app) cannot import your component |
Changing the tsup build scripts in package.json | Breaks the CJS/ESM dual output required for Metro and production bundling |
Next Steps
Mobile feature guides:
- SDK Reference — SDK packages, methods, and usage
- Extension Template Catalog — Scaffold from DI template catalog
- Mobile Playground — Preview features in the banking-style sandbox
- Platform Capabilities (Local) — How local development works with mock data
- Host App Integration — Repository structure and submission process